<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>一键委案功能接口设计文档</title>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
            line-height: 1.6;
            color: #333;
            max-width: 1200px;
            margin: 0 auto;
            padding: 20px;
            background-color: #f5f5f5;
        }
        .doc-container {
            background: white;
            border-radius: 8px;
            padding: 30px;
            box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
        }
        .section {
            margin-bottom: 40px;
            padding: 20px;
            border: 1px solid #e8e8e8;
            border-radius: 6px;
            background: #fafafa;
        }
        .section-title {
            font-size: 20px;
            font-weight: 600;
            color: #1890ff;
            margin-bottom: 20px;
            padding-bottom: 10px;
            border-bottom: 2px solid #1890ff;
        }
        .api-item {
            margin: 15px 0;
            padding: 15px;
            background: white;
            border-radius: 6px;
            border-left: 4px solid #52c41a;
        }
        .api-name {
            font-weight: 600;
            color: #262626;
            margin-bottom: 8px;
        }
        .api-url {
            font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
            background: #f6f8fa;
            padding: 4px 8px;
            border-radius: 4px;
            font-size: 14px;
            color: #d73a49;
        }
        .api-description {
            color: #666;
            margin: 8px 0;
        }
        .api-params {
            margin: 10px 0;
        }
        .param-item {
            margin: 5px 0;
            padding: 5px 10px;
            background: #f0f9ff;
            border-radius: 4px;
            font-size: 14px;
        }
        .param-name {
            font-weight: 500;
            color: #1890ff;
        }
        .param-type {
            color: #666;
            font-style: italic;
        }
        .workflow-step {
            display: flex;
            align-items: center;
            margin: 15px 0;
            padding: 15px;
            background: white;
            border-radius: 8px;
            border: 1px solid #e8e8e8;
        }
        .step-number {
            width: 30px;
            height: 30px;
            border-radius: 50%;
            background: #1890ff;
            color: white;
            display: flex;
            align-items: center;
            justify-content: center;
            font-weight: 600;
            margin-right: 15px;
        }
        .step-content {
            flex: 1;
        }
        .step-title {
            font-weight: 600;
            color: #262626;
            margin-bottom: 5px;
        }
        .step-description {
            color: #666;
            font-size: 14px;
        }
        .code-block {
            background: #f6f8fa;
            border: 1px solid #e1e4e8;
            border-radius: 6px;
            padding: 16px;
            margin: 10px 0;
            font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
            font-size: 14px;
            overflow-x: auto;
        }
        .highlight {
            background: #fff2e8;
            padding: 2px 4px;
            border-radius: 3px;
            font-weight: 500;
        }
        .warning {
            background: #fff7e6;
            border: 1px solid #ffd591;
            border-radius: 6px;
            padding: 12px;
            margin: 10px 0;
        }
        .success {
            background: #f6ffed;
            border: 1px solid #b7eb8f;
            border-radius: 6px;
            padding: 12px;
            margin: 10px 0;
        }
    </style>
</head>
<body>
    <div class="doc-container">
        <h1>🚀 一键委案功能接口设计文档</h1>
        
        <div class="section">
            <div class="section-title">📋 功能概述</div>
            <p>一键委案功能实现了从Excel文件上传到最终委案完成的完整自动化流程，包括文件上传、初审、终审、定时任务、委案配置和委案执行等步骤。</p>
        </div>

        <div class="section">
            <div class="section-title">🔄 完整工作流程</div>
            
            <div class="workflow-step">
                <div class="step-number">1</div>
                <div class="step-content">
                    <div class="step-title">上传Excel文件</div>
                    <div class="step-description">用户选择Excel文件，系统自动上传到OSS并保存附件信息</div>
                </div>
            </div>
            
            <div class="workflow-step">
                <div class="step-number">2</div>
                <div class="step-content">
                    <div class="step-title">执行初审</div>
                    <div class="step-description">调用初审接口，将案件状态更新为初审通过</div>
                </div>
            </div>
            
            <div class="workflow-step">
                <div class="step-number">3</div>
                <div class="step-content">
                    <div class="step-title">执行终审</div>
                    <div class="step-description">调用终审接口，将案件状态更新为终审通过</div>
                </div>
            </div>
            
            <div class="workflow-step">
                <div class="step-number">4</div>
                <div class="step-content">
                    <div class="step-title">执行定时任务</div>
                    <div class="step-description">调用定时任务接口，处理委案和委案撤案的任务</div>
                </div>
            </div>
            
            <div class="workflow-step">
                <div class="step-number">5</div>
                <div class="step-content">
                    <div class="step-title">配置委案参数</div>
                    <div class="step-description">用户选择委案商、设置批次名称等委案参数</div>
                </div>
            </div>
            
            <div class="workflow-step">
                <div class="step-number">6</div>
                <div class="step-content">
                    <div class="step-title">执行委案</div>
                    <div class="step-description">获取委案初始化数据，执行委案操作</div>
                </div>
            </div>
            
            <div class="workflow-step">
                <div class="step-number">7</div>
                <div class="step-content">
                    <div class="step-title">完成流程</div>
                    <div class="step-description">显示执行结果，支持重新开始或返回列表</div>
                </div>
            </div>
        </div>

        <div class="section">
            <div class="section-title">🔌 涉及的主要接口</div>
            
            <div class="api-item">
                <div class="api-name">1. 文件上传相关接口</div>
                <div class="api-url">getOSSSignature</div>
                <div class="api-description">获取OSS上传签名，用于文件上传到阿里云OSS</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">accessType</span>: <span class="param-type">string</span> - 访问类型 (CASE_FILE)
                    </div>
                    <div class="param-item">
                        <span class="param-name">fileName</span>: <span class="param-type">string</span> - 文件名
                    </div>
                    <div class="param-item">
                        <span class="param-name">objectId</span>: <span class="param-type">string</span> - 对象ID
                    </div>
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">2. OSS文件上传</div>
                <div class="api-url">OssUpload</div>
                <div class="api-description">将文件上传到阿里云OSS存储</div>
            </div>
            
            <div class="api-item">
                <div class="api-name">3. 保存文件附件</div>
                <div class="api-url">saveAttachment</div>
                <div class="api-description">保存上传文件的信息到系统数据库</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">fileType</span>: <span class="param-type">string</span> - 文件MIME类型
                    </div>
                    <div class="param-item">
                        <span class="param-name">url</span>: <span class="param-type">string</span> - 文件存储路径
                    </div>
                    <div class="param-item">
                        <span class="param-name">objectId</span>: <span class="param-type">string</span> - 对象ID
                    </div>
                    <div class="param-item">
                        <span class="param-name">fileName</span>: <span class="param-type">string</span> - 文件名
                    </div>
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">4. 初审接口</div>
                <div class="api-url">auditUploadRecordEntrust</div>
                <div class="api-description">执行案件初审，将案件状态更新为初审通过</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">id</span>: <span class="param-type">string</span> - 案件ID
                    </div>
                    <div class="param-item">
                        <span class="param-name">state</span>: <span class="param-type">string</span> - 状态 (AUDIT_SUCCESS)
                    </div>
                    <div class="param-item">
                        <span class="param-name">tsToken</span>: <span class="param-type">string</span> - 身份验证令牌
                    </div>
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">5. 终审接口</div>
                <div class="api-url">finalAuditUploadRecordEntrust</div>
                <div class="api-description">执行案件终审，将案件状态更新为终审通过</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">id</span>: <span class="param-type">string</span> - 案件ID
                    </div>
                    <div class="param-item">
                        <span class="param-name">state</span>: <span class="param-type">string</span> - 状态 (AUDIT_SUCCESS)
                    </div>
                    <div class="param-item">
                        <span class="param-name">tsToken</span>: <span class="param-type">string</span> - 身份验证令牌
                    </div>
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">6. 定时任务接口</div>
                <div class="api-url">useScheduledTask.executeTask</div>
                <div class="api-description">执行定时任务，处理委案和委案撤案的任务</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">taskId</span>: <span class="param-type">string</span> - 任务ID (可选)
                    </div>
                    <div class="param-item">
                        <span class="param-name">jobGroup</span>: <span class="param-type">string</span> - 任务组 (默认: '5')
                    </div>
                    <div class="param-item">
                        <span class="param-name">jobDesc</span>: <span class="param-type">string</span> - 任务描述
                    </div>
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">7. 获取委案商列表</div>
                <div class="api-url">getEntrustByAId</div>
                <div class="api-description">获取可用的委案商列表</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">tsToken</span>: <span class="param-type">string</span> - 身份验证令牌
                    </div>
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">8. 获取委案初始化数据</div>
                <div class="api-url">countEntrustClient</div>
                <div class="api-description">获取委案初始化数据，包括客户数量和贷款数量</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">loanIds</span>: <span class="param-type">string[]</span> - 贷款ID数组
                    </div>
                    <div class="param-item">
                        <span class="param-name">tsToken</span>: <span class="param-type">string</span> - 身份验证令牌
                    </div>
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">9. 委案提交接口</div>
                <div class="api-url">entrustClient</div>
                <div class="api-description">执行委案操作，将案件委派给指定的委案商</div>
                <div class="api-params">
                    <div class="param-item">
                        <span class="param-name">loanIds</span>: <span class="param-type">string[]</span> - 贷款ID数组
                    </div>
                    <div class="param-item">
                        <span class="param-name">entrustBId</span>: <span class="param-type">string</span> - 委案商ID
                    </div>
                    <div class="param-item">
                        <span class="param-name">batchName</span>: <span class="param-type">string</span> - 批次名称
                    </div>
                    <div class="param-item">
                        <span class="param-name">isInvalidRule</span>: <span class="param-type">boolean</span> - 是否跳过同客户限制
                    </div>
                    <div class="param-item">
                        <span class="param-name">clients</span>: <span class="param-type">number</span> - 客户数量
                    </div>
                    <div class="param-item">
                        <span class="param-name">loans</span>: <span class="param-type">number</span> - 贷款数量
                    </div>
                </div>
            </div>
        </div>

        <div class="section">
            <div class="section-title">💻 技术实现细节</div>
            
            <div class="api-item">
                <div class="api-name">文件上传流程</div>
                <div class="code-block">
// 1. 获取OSS签名
const signature = await getOSSSignature({
  accessType: 'CASE_FILE',
  fileName: file.name,
  objectId: caseId,
  protocol: 'https'
});

// 2. 上传文件到OSS
await OssUpload(signature.result, file);

// 3. 保存附件信息
await saveAttachment({
  fileType: file.type,
  url: signature.result.dir,
  objectId: caseId,
  fileName: file.name,
  uploadType: 'CASE_FILE',
  bizType: 'CASE_FILE',
  protocol: 'https'
});
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">审核流程</div>
                <div class="code-block">
// 1. 初审
const preAuditResult = await auditUploadRecordEntrust({
  id: caseId,
  state: 'AUDIT_SUCCESS',
  tsToken: localStorage.getItem('tsToken')
});

// 2. 终审
const finalAuditResult = await finalAuditUploadRecordEntrust({
  id: caseId,
  state: 'AUDIT_SUCCESS',
  tsToken: localStorage.getItem('tsToken')
});
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">定时任务执行</div>
                <div class="code-block">
// 执行定时任务
const { executeTask } = useScheduledTask();
const taskResult = await executeTask();
                </div>
            </div>
            
            <div class="api-item">
                <div class="api-name">委案流程</div>
                <div class="code-block">
// 1. 获取委案初始化数据
const countResult = await countEntrustClient({
  loanIds: [caseId],
  tsToken: localStorage.getItem('tsToken')
});

// 2. 执行委案
const entrustResult = await entrustClient({
  loanIds: [caseId],
  entrustBId: entrustForm.entrustBId,
  batchName: entrustForm.batchName,
  isInvalidRule: entrustForm.isInvalidRule,
  clients: countResult.result?.clients || 0,
  loans: countResult.result?.loans || 0,
  tsToken: localStorage.getItem('tsToken')
});
                </div>
            </div>
        </div>

        <div class="section">
            <div class="section-title">⚠️ 注意事项</div>
            
            <div class="warning">
                <strong>文件上传限制：</strong>
                <ul>
                    <li>文件大小限制：50MB</li>
                    <li>支持格式：.xlsx, .xls</li>
                    <li>需要有效的tsToken进行身份验证</li>
                </ul>
            </div>
            
            <div class="warning">
                <strong>审核流程要求：</strong>
                <ul>
                    <li>案件必须处于"待审核"状态才能进行一键委案</li>
                    <li>初审和终审必须按顺序执行</li>
                    <li>每个步骤都有错误处理机制</li>
                </ul>
            </div>
            
            <div class="warning">
                <strong>委案配置要求：</strong>
                <ul>
                    <li>必须选择有效的委案商</li>
                    <li>批次名称不能为空</li>
                    <li>需要获取委案初始化数据才能执行委案</li>
                </ul>
            </div>
        </div>

        <div class="section">
            <div class="section-title">🎯 优化建议</div>
            
            <div class="success">
                <strong>性能优化：</strong>
                <ul>
                    <li>文件上传支持断点续传</li>
                    <li>审核流程支持并发执行</li>
                    <li>定时任务支持异步执行</li>
                </ul>
            </div>
            
            <div class="success">
                <strong>用户体验：</strong>
                <ul>
                    <li>实时进度显示</li>
                    <li>详细的错误提示</li>
                    <li>支持操作回滚</li>
                </ul>
            </div>
            
            <div class="success">
                <strong>安全性：</strong>
                <ul>
                    <li>文件类型验证</li>
                    <li>权限控制</li>
                    <li>操作日志记录</li>
                </ul>
            </div>
        </div>

        <div class="section">
            <div class="section-title">📊 接口调用统计</div>
            
            <div class="api-item">
                <div class="api-name">完整流程接口调用次数</div>
                <ul>
                    <li>文件上传相关：3次 (getOSSSignature + OssUpload + saveAttachment)</li>
                    <li>审核流程：2次 (auditUploadRecordEntrust + finalAuditUploadRecordEntrust)</li>
                    <li>定时任务：1次 (executeTask)</li>
                    <li>委案相关：3次 (getEntrustByAId + countEntrustClient + entrustClient)</li>
                    <li><strong>总计：9次接口调用</strong></li>
                </ul>
            </div>
        </div>
    </div>
</body>
</html>
